LEGEND

The LEGEND function adds a legend to 2D or 3D line plots, bar plots, contour plots, or vector plots. By default, for line plots, bar plots, and contour plots the NAME property of the graphic item is used for the label within the legend. By default, for vector plots the mean magnitude of the vector field is used for length of the sample vector and for the legend label. In both cases the default label can be overridden with the LABEL property.

Example

Copy and paste the following code to the IDL command line to generate the above graphic: y

; Define the data variables.

theory = SIN(2.0*FINDGEN(201)*!PI/25.0)*EXP(-0.02*FINDGEN(201))

observed = theory + RANDOMU(seed,201)*0.4-0.2

 

; Display the first plot.

plot1 = PLOT(observed, 'b2', NAME='Observed')

 

; Display the second plot.

plot2 = PLOT(theory, /OVERPLOT, 'r2', NAME='Theory')

 

; Add the legend.

leg = LEGEND(TARGET=[plot1,plot2], POSITION=[185,0.9], $

/DATA, /AUTO_TEXT_COLOR)

See the bottom for an example using a vector plot.

Syntax

graphic = LEGEND([, Keywords=value][, Properties=value])

Keywords

Keywords are applied only during the initial creation of the graphic.

[, /DATA] [, /DEVICE] [, /NORMAL] [, /RELATIVE] [, TARGET=variable]

Properties

Properties can be set as keywords to the function during creation, or retrieved or changed using the "." notation after creation.

AUTO_TEXT_COLOR, COLOR, FONT_NAME, FONT_SIZE, FONT_STYLE, HORIZONTAL_ALIGNMENT, HORIZONTAL_SPACING, LABEL, LINESTYLE, ORIENTATION, POSITION, SAMPLE_ANGLE, SAMPLE_MAGNITUDE, SAMPLE_WIDTH, SHADOW, TEXT_COLOR, THICK, TRANSPARENCY, UNITS, UVALUE, VERTICAL_ALIGNMENT, VERTICAL_SPACING, WINDOW

Methods

Close  

ConvertCoord

CopyWindow

Delete

Erase

Order 

Print

Refresh

Rotate

Save

Scale

Select

Translate

Return Value

The LEGEND function returns a reference to the created graphic. Use the returned reference to manipulate the graphic after creation by changing properties or calling methods.

Keywords

Keywords are applied only during the initial creation of the graphic.

DATA

Set this keyword if the input POSITION is in data coordinates. The coordinates will then be automatically converted to normalized coordinates before inserting the legend into the annotation layer.

DEVICE

Set this keyword if the input POSITION is in device coordinates (pixels). The coordinates will then be automatically converted to normalized coordinates before inserting the legend into the annotation layer.

NORMAL

Set this keyword if the input POSITION is in normalized ( [0, 1] ) coordinates (the default).

RELATIVE

Set this keyword to indicate that the input arguments are specified in normalized [0,1] coordinates, relative to the axis range of the TARGET's dataspace. If the TARGET keyword is not specified, then setting /RELATIVE is the same as setting /NORMAL.

Note: When using /RELATIVE, even though the coordinates are relative to the TARGET's dataspace, the graphic is added to the annotation layer, not to the dataspace.

TARGET

Set this keyword to the visualization to which the legend should be associated. If TARGET is not specified any currently selected objects will be used. If no suitable targets are found no legend will be created.

Properties

AUTO_TEXT_COLOR

Set this property to true (1) to draw the text labels using the same color as the associated plot lines. If this property is set then the TEXT_COLOR property is ignored. The default is false (0).

COLOR

Set this property to a string or RGB vector that specifies the color of the outline.

HORIZONTAL_ALIGNMENT

The horizontal alignment of the legend with respect to the position. This is a value between 0 and 1 where 1 specifies right-aligned (the default). This can also be a string with the following options: 'LEFT', 'CENTER', or 'RIGHT'.

HORIZONTAL_SPACING

The horizontal spacing between items in normalized units. The default is 0.04.

LINESTYLE

Set this property to an integer or string specifying the line style for the outline.

The following table lists the index values and strings you can use with this property.

Index

Property

Description

0

'solid_line', '-'(dash)

solid line

1

'dot', ':'(colon)

dotted

2

'dash', '--' (double dashes)

dashed

3

'dash_dot', '-.'

dash dot

4

'dash_dot_dot_dot', '-:'

dash dot dot dot

5

'long_dash', '__' (two underscores)

long dash

6

'none', ' ' (space)

no line

You can also set the line style to a two-element vector, [repeat, bitmask], specifying a stippling pattern. The repeat indicates the number of times that individual bits in the bitmask should be repeated. (That is, if three consecutive 0’s appear in the bitmask and the value of repeat is 2, then the line that is drawn will have six consecutive bits turned off.) The value of repeat must be an integer between 1 and 255. The bitmask indicates which pixels are drawn and which are not along the length of the line. The bitmask should be specified as a 16-bit hexadecimal value. For example, [2, 'AAAA'X] describes a dashed line with very short dashes of length 2 bits each.

ORIENTATION

The orientation of the legend. Setting this value to one (1) denotes a horizontal legend, the default is a vertical legend.

POSITION

Set this property to set the location of the legend. POSITION is specified as a 2 element vector: [X, Y], defining the upper right corner of the legend. If the DEVICE property is set, the units are given in device units (pixels).

SHADOW

Set this property to true (1) to turn on the legend shadow, or to false (0) to turn off the shadow. The default value is 0.

THICK

Set this property to a value between 0 and 10 that specifies the line thickness of the outline. A thickness of 0 displays a thin hairline on the chosen device. The default value is 1.

TRANSPARENCY

An integer from 0-100 giving the percent transparency.

UVALUE

Set this property to an IDL variable of any data type.

VERTICAL_ALIGNMENT

The vertical alignment of the legend with respect to the position. This is a value between 0 and 1 where 1 specifies top aligned (the default). This can also be a string with the following options: 'TOP', 'CENTER', or 'BOTTOM'.

VERTICAL_SPACING

The vertical spacing between items in normalized units. The default is 0.03.

WINDOW (Get Only)

This property retrieves a reference to the WINDOW object which contains the graphic.

Legend Item Properties

The following properties apply to the individual legend items within the legend. These properties can be set on initial creation of the legend, and will be passed down to all of the newly-created legend items. The properties can also be set on a legend item after creation by retrieving the legend item and then using the "." notation.

FONT_NAME

Set this property equal to a string specifying the IDL or system font. The default value is "DejaVuSans".

FONT_SIZE

Set this property equal to an integer specifying the font size. The default value is 9 points.

FONT_STYLE

A string or integer containing the font style. Allowed values are:

Integer

String

Resulting Style

0

"Normal" or "rm"

Default (roman)

1

"Bold" or "bf"

Bold

2

"Italic" or "it"

Italic

3

"Bold italic" or "bi"

Bold italic

LABEL

Set this property to a string giving the label for the legend item. If this property is set then the default label will not be used. Set this property to an empty string to go back to using the default label.

You can add Greek letters and mathematical symbols using a TeX-like syntax. These symbols need to be enclosed within a pair of "$" characters. See Adding Mathematical Symbols and Greek Letters to the Text String for details on the available symbols.

SAMPLE_ANGLE

The angle of the sample line or arrow, in degrees. The default value is zero, which gives a horizontal line for line plots, and a right-pointing arrow for vector plots.

SAMPLE_MAGNITUDE

Note: This keyword only applies to legend items for vector plots.

Set this property to either a case-insensitive string or a floating-point number giving the length of the sample vector. Possible values are:

The arrow displayed in the legend is scaled to match the chosen length, relative to the maximum magnitude of the vector plot. This property is only used for legend items for vector plots, and is ignored for all other legend items.

Note: If the LABEL property is set, then the SAMPLE_MAGNITUDE will still be used to scale the length of the sample arrow, but will not be used to label the legend item. For example, if your vector data was in "miles per hour" but you wanted to display the length in "km/hr", you might set the SAMPLE_MAGNITUDE to 62, but then set the LABEL to "100 km/hr".

SAMPLE_WIDTH

The width of the line sample, in normalized units. The default value is 0.15.

For line plots, increasing the SAMPLE_WIDTH will also increase the number of plot symbols on the legend item. A sample width of 0 gives 1 plot symbol. A sample width of 0.01–0.19 gives 2 plot symbols, 0.20–0.39 gives 3 plot symbols, etc.

TEXT_COLOR

Set this property to a string or RGB vector that specifies the color of the text.

UNITS

Set this property to a string giving the units for the vector plot. This string will then be appended to the sample magnitude label in the legend item. If the LABEL property is set then this property is ignored. This property is only used for legend items for vector plots, and is ignored for all other legend items.

You can add Greek letters and mathematical symbols using a TeX-like syntax. These symbols need to be enclosed within a pair of "$" characters. See Adding Mathematical Symbols and Greek Letters to the Text String for details on the available symbols.

Retrieving Individual Legend Items

Once a legend is created, the individual legend items can be retrieved using standard array indexing. Once a legend item is retrieved, you can change any of the properties on that legend item. For example:

t = FINDGEN(101)/10

p1 = PLOT(SIN(t), '-ro')

p2 = PLOT(COS(t), '-go', /OVERPLOT)

leg = LEGEND(TARGET=[p1,p2])

 

; Retrieve the first and second legend items, change the labels

leg[0].label = "Sin"

leg[1].label = "Cos"

HELP, leg[0]

HELP, leg[1]

HELP, leg[0:1]

IDL prints:

<Expression> LEGENDITEM <19018>

<Expression> LEGENDITEM <19019>

<Expression> OBJREF = Array[2]

Additional Example

This example demonstrates how to add a legend to a vector plot.

; Set up the map projection, grid, and continents.

m = MAP('Equirectangular', LIMIT=[0,-150,60,-45], $

LABEL_POSITION=0, COLOR='light gray', LABEL_COLOR='black')

m1 = MAPCONTINENTS(FILL_COLOR='light gray')

 

; Read the wind data, create a vector plot

RESTORE, FILEPATH('globalwinds.dat', $

SUBDIR=['examples','data'])

vec = VECTOR(u, v, x, y, /OVERPLOT, LENGTH_SCALE=2)

 

; Add the legend

leg = LEGEND(SAMPLE_MAGNITUDE=10, UNITS='$m s^{-1}$', $

POSITION=m.MapForward(-45,61), /DATA, $

VERTICAL_ALIGNMENT='bottom')

Note that we use the MapForward method to determine the position of the legend in the upper right of the map. Also note that we use the SAMPLE_MAGNITUDE property to override the default sample vector length.

Version History

8.0

Introduced

8.1

Added the UVALUE property.

The THICK property was changed to accept a value between 0 and 10.

8.2

Added support for legends for vector plots. Added Legend Item properties: LABEL, SAMPLE_ANGLE, SAMPLE_MAGNITUDE, UNITS.

Changed behavior of POSITION keyword to use upper-right of legend.

8.2.3

Added the ability to use a stippling pattern for LINESTYLE.
8.6 Changed default font name and font size.

See Also

!COLOR, MAP, MAPCONTINENTS, PLOT, PLOT3D, VECTOR